ViewIt provides a high-level interface to the File Manager that facilitates opening of the standard file dialogs, tracking file locations, and resetting file types. Files are typically identified by a file name and a 2-byte "working directory reference number" which identifies the directory (folder) in which the file is located. The current directory is the directory to which file operations will apply unless some other directory is specified.
The displayed directory shown in the standard file dialogs opened by StdOpn and StdSav will be the last directory searched by the user, whether that directory is the current one to which files are saved or not. In most cases this is the preferred behavior since the user expects these dialogs to display the last directory searched. In other cases you may need to display a different directory, and can do this via parameter a in StdOpn and StdSav, or b in SetRef.
If working with FORTRAN, note that though working directory reference numbers are 2-byte integers, you may want to store them in 4-byte integer variables since that is the required size of parameters passed with FaceWare commands. To set the current directory to the folder containing the program, for example, SetRef can be passed fApplVRef (a 2-byte integer). You must either force a type conversion using the "int" function or first assign fApplVRef to a 4-byte integer:
integer*4 myFolder
...
myFolder = fApplVRef
call FaceIt(0,SetRef,myFolder,0,0,0)
Name Number Parameters & Variables used
StdOpn 201 a,b,c,d,uString,uName,uResult,uI2
Displays standard "Open" file dialog where b, c, and d define the initial position of the dialog (same use as with the MovRec command described in "Window Utilities"), uName (if not empty) is used to redefine the text displayed in the "Open" button, and uString can contain up to 21 12-character "records" to designate file filtering. A working directory reference number can be optionally passed in parameter a to change the default displayed directory.
Each 12-character file filtering "record" in uString consists of an optional 4-character file type, 4-character file creator, and 1 to 4 character extension (w/o a leading "."). Use spaces to designate entries that should be ignored, and all records except the last record must be exactly 12 characters long. "TEXTMYPGtextPICT pic DATA", for example, consists of three records which would cause ViewIt to display all files of type "TEXT" and creator "MYPG" with the extension ".text", and all files of type "PICT" with the extension ".pic", and all files of type "DATA". If uString is empty, then all files are displayed (no filtering is done).
When the dialog is closed, the variable uResult returns with the button pressed (1 = Open, 2 = Cancel). If the Open button is pressed, then uName is set equal to the name of the file, the default volume or directory is set to the disk or HFS folder which contains the file, uI2 is set equal to the working directory reference number, and uString is set equal to the type, creator, and extension of the chosen file in a single filter record like that described above.
For example, suppose you wished to have the user choose a file from a standard file dialog that showed only files of type "TEXT" and creator "MYPG", had "Run" as its default button, and was centered horizontally, 1/3 from the top of the main screen. The following code fragment would do this:
uString := 'TEXTMYPG';
uName := 'Run';
FaceIt(nil,StdOpn,0,0,4,1);
if (uResult = 1) then
[uName contains chosen file name]
A common mistake is to forget that the variable uName is a scratch variable that can be clobbered by other calls to the FaceIt dispatching procedure. Always save the file name returned in uName to a program string variable if it is not going to be used with or before the next "FaceIt" call.
FILTER NOTE: When filtering by creator, remember that programs under development (and the files they create) may not yet have been given the proper creator designation.
FORTRAN NOTE: To set a string such as uName in FORTRAN to an empty string, set the string equal to a single space.
StdSav 202 a,b,c,d,uString,uName,uResult,uI2
Displays the standard "Save As" dialog where b, c, and d define the initial position of the dialog (same use as with the MovRec command described in "Window Utilities"), uString is used as the prompt string, and uName as the default file name. A working directory reference number can be optionally passed in parameter a to change the default displayed directory.
When the dialog is closed, uResult returns the button pressed (1 = Save, 2 = Cancel). If the Save button was pressed, then uName is set equal to the file name entered by the user, the default volume or directory is set to the disk or HFS folder selected by the user, and uI2 is set equal to the working directory reference number.
GetRef 205 a,uI2,uResult
Returns in uI2 the working directory reference number designated by a where a = 0 returns the current directory and a = 1 returns the active System folder. The variable uResult will contain a value less than zero (an OSErr) if an error occurs. uString and uName are not changed by calls to GetRef. This command is primarily provided for those programmers who do not have access to the high-level toolbox routine GetVol.
SetRef 206 a,b,uResult
Resets the current directory to that designated by a where a is either a working directory reference number or a = 1 designates the active System folder. (If a = 0, the current directory is not changed.) If b = 1, then the directory displayed by standard file dialogs will also be set equal to that designated by a. uResult will return a value less than zero (an OSErr) if an error occurs. uString and uName are not changed by calls to SetRef.
WARNING: See the note at the beginning of this topic about the need to pass working directory reference numbers as 4-byte integers.
SetTyp 208 a,uString,uName,uResult
Resets the file type and/or creator of the file whose name is given by uName in the directory designated by a where a is either a working directory reference number, or a = 0 designates the current directory, or a = 1 designates the active System folder. The new file type and creator are designated by the first 8 characters of uString using the same scheme as that defined above for StdOpn. uResult will return a value less than zero (an OSErr) if an error occurs. This command is primarily provided for those programmers who do not have access to the high-level toolbox routine SetFInfo.
